class PickHelper

Parent: Object

Class Index

Methods:all_picked, best_picked, count, depth_at, do_pick, element_at, init, leaf_at, path_at, pick_segment, picked_edge, picked_element, picked_face, test_point, transformation_at, view

Sample Code:pickhelpertooltests.rb

Instance Methods

all_picked

The all_picked method retrieves an array of everything that was picked (all entities under the cursor when a mouse or keyboard event occurred).

Syntax:

picked = pickhelper.all_picked

Arguments:

Return Value:

picked - an array of entities picked

Comments:

You must have called do_pick before calling this method.

Example:

ph = view.pick_helper
ph.do_pick x,y
picked = ph.all_picked

best_picked

The best_picked method is used to retrieve the "best" entity picked (entity that you would have picked if you were using the select tool).

Syntax:

entity = pickhelper.best_picked

Arguments:

Return Value:

entity - the best picked entity

Comments:

You must have called do_pick prior to calling this method.

Example:

ph = view.pick_helper
ph.do_pick x,y
best = ph.best_picked

count

The count method is used to count the number of entities picked (number of pick records)

Syntax:

number = pickhelper.count

Arguments:

Return Value:

number - the number of entities picked

Comments:

Example:

ph = view.pick_helper
ph.do_pick x,y
num = ph.count

depth_at

The depth_at method retrieves the depth of one of the currently picked entities in the list of pick records.

Syntax:

depth = pickhelper.depth_at index

Arguments:

index - a number from 1 to number of items picked

Return Value:

depth - the depth of the entity if successful

Comments:

Returns 1 if element is outside a component or group.

Example:

ph = view.pick_helper
ph.do_pick x,y
depth = ph.depth_at 1

do_pick

The do_pick method is used to perform the initial pick. This method is generally called before any other methods in the PickHelper class.

Syntax:

numpicked = pickhelper.do_pick x, y

Arguments:

x - x screen coordinate for the pick

y - y screen coordinate for the pick

Return Value:

numpicked - the number of entities picked

Comments:

Returns the number of entities picked. The x and y values are the screen coordinates of the point at which would want to do a pick.

Example:

ph = view.pick_helpernum =  ph.do_pick x,y

element_at

The element_at method is used to retrieve a specific entity in the list of picked elements.

Syntax:

entity = pickhelper.element_at index

Arguments:

index - a number from 0 to number of items picked

Return Value:

entity - the entity at the index position in the list of picked entities.

Comments:

Example:

ph = view.pick_helper
ph.do_pick x,y
# Returns the element at a specific spot in the list of
# elements picked.
element = ph.element_at 0    

init

The init method is used to initialize the PickHelper for testing points.

Syntax:

pickhelper = pickhelper.init x, y

pickhelper = ph.init x, y, aperture

Arguments:

 x - x screen coordinate for the pick

y - y screen coordinate for the pick                  

aperture -

Return Value:

pickhelper - a PickHelper object

Comments:

You do not normally need to call this method, but you can use this if you want to call test_point on a lot of points.

If the optional aperture is given, it is given in pixels.

Example:

ph = view.pick_helper
phnew = ph.init x, y

leaf_at

The leaf_at method retrieves the deepest thing in a pick path.  

Syntax:

entity = pickhelper.leaf_at index

Arguments:

index - a number from 1 to number of items picked

Return Value:

entity - the leaf entity

Comments:

For example, if you have a face that is within a component that is within another component, leaf_at returns the face.

Example:

ph = view.pick_helper
# Returns nil
phnew = ph.leaf_at 1

path_at

The path_at method is used to retrieve the entire path for an entity in the pick list (as an array).

Syntax:

array = pickhelper.path_at index

Arguments:

index - a number from 1 to number of items picked

Return Value:

array - an array of entities including the leaf

Comments:

Example:

ph = view.pick_helper
# Returns nil
path = ph.path_at 1

pick_segment

The pick_segment method is used to pick a segment of a polyline curve that is defined by an array of points.

Syntax:

index = pickhelper.pick_segment point1, point2, ... <apature>

index = pickhelper.pick_sgement [point1, point2, ...] <apature>

Arguments:

point1, point2, ... - a series of Point3d objects in the polyline

[point1, point2, ...] - an array of Point3d objects in the polyline

Return Value:

index - an index of the point in the array if you clicked on a point or an index of a segment if you clicked on a segment (if successful)

Comments:

See bezier.rb

If you click on a point in a polyline curve, the index of the point in the curve is returned (starting at 0). If you click on a segment in the polyline curve, the index of the segment is returned. Segments start at index -1 (for the segment connecting the first two points) and increase by a factor of -1 (for example, the segment connecting second and third point is -2).

Example:

point1 = Geom::Point3d.new 0,0,0
point2 = Geom::Point3d.new 10,0,0
ph = view.pick_helper
# Returns -1 or 0
path = ph.pick_segment point1, point2

picked_edge

The picked_edge method is used to retrieve the "best" Edge picked

Syntax:

edge =pickhelper.picked_edge

Arguments:

Return Value:

edge - an Edge object if successful

Comments:

Example:

ph = view.pick_helper
ph.do_pick x,y
best = ph.picked_edge

picked_element

The picked_element method retrieves the best drawing element, that is not an edge or a face, picked.

Syntax:

element =pickhelper.picked_element

Arguments:

Return Value:

element - a drawing element that is not an edge or face if successful

Comments:

Returns nil if there was nothing picked.

You must have called do_pick before calling this method.

Example:

ph = view.pick_helper
ph.do_pick x,y
best = ph.picked_element

picked_face

The picked_face method is used to retrieve the best face picked.

Syntax:

face =pickhelper.picked_face

Arguments:

Return Value:

face - a Face object if successful.

Comments:

Returns nil if there were no faces picked.

You must have called do_pick before calling this method.

Example:

ph = view.pick_helper
ph.do_pick x,y
best = ph.picked_face

test_point

The test_point method is used to test a point to see if it would be selected using the default or given pick aperture.

Syntax:

ok = pickhelper.test_point(pt)

ok = pickhelper.test_point point, x, y

ok = pickhelper.test_point point, x, y, aperture

Arguments:

Return Value:

Comments:

In the first form, you must have initialized the PickHelper using the init method. This is more efficient if you want to test a lot of points using the same screen point.

In the second and third forms, it initializes the PickHelper using a screen point and an optional pick aperture.

Example:

point = Geom::Point3d.new 0,0,0
ph = view.pick_helper
ph.do_pick x,y
# returns nil
status = ph.test_point point

transformation_at

The transformation_at method is used to get a transformation at a specific index in the pick helper.

Syntax:

transformation = pickhelper.transformation_at index

Arguments:

index - the index where the transformation should be retrieved.

Return Value:

transformation - the transformation found

Comments:

The index represents the depth (whether the transformation is encapsulated in a component or group). A depth of 1 represents no encapsulation.

Example:

ph = view.pick_helper
ph.do_pick x,y
t = ph.transformation_at 1

view

The view method is used to retrieve the View that this PickHelper is associated with.

Syntax:

view = pickhelper.view

Arguments:

Return Value:

view - the current View object associated with the pick helper

Comments:

Example:

ph = view.pick_helper
ph.do_pick x,y
v = ph.view